electron-builder 打包配置（简化版本）
概述
本节提供 electron-builder 的快速上手配置。如需快速搭建 Electron 打包流程，可直接参考本节配置；如需深入了解每个配置项，请参考后续的详解版本章节。
配置文件结构
electron-builder 支持三种配置文件格式：
| 格式 | 文件名 | 适用场景 |
|---|---|---|
| JavaScript | electron-builder.config.js | 动态配置、条件判断 |
| TypeScript | electron-builder.config.ts | 类型安全、IDE 提示 |
| JSON（package.json） | "build" 字段 | 简单项目 |
最简配置
// electron-builder.config.ts
import type { Configuration } from 'electron-builder'
const config: Configuration = {
appId: 'com.example.myapp',
productName: 'My App',
directories: {
output: 'dist',
buildResources: 'build'
},
files: [
'dist/**/*',
'!dist/**/*.map'
],
mac: {
category: 'public.app-category.productivity',
target: ['dmg']
},
win: {
target: ['nsis']
},
linux: {
target: ['AppImage']
}
}
export default config
typescript
平台打包格式对比
| 平台 | 格式 | 说明 | 文件后缀 |
|---|---|---|---|
| macOS | dmg | 磁盘镜像安装包（推荐） | .dmg |
| macOS | pkg | macOS 安装包格式 | .pkg |
| macOS | zip | 压缩包（用于自动更新） | .zip |
| Windows | nsis | NSIS 安装程序（推荐） | .exe |
| Windows | portable | 免安装便携版 | .exe |
| Windows | msi | Windows Installer | .msi |
| Linux | AppImage | 通用格式（推荐） | .AppImage |
| Linux | deb | Debian/Ubuntu | .deb |
| Linux | rpm | Fedora/CentOS | .rpm |
各平台配置详解
macOS 配置
mac: {
category: 'public.app-category.developer-tools', // App Store 分类
target: [
{ target: 'dmg', arch: ['arm64', 'x64'] } // 同时支持 Intel 和 Apple Silicon
],
icon: 'build/icon.icns', // 图标路径（256x256 icns 格式）
hardenedRuntime: true, // 加固运行时（公证必需）
darkModeSupport: true // 暗黑模式支持
}
typescript
macOS category 常用值：
public.app-category.productivity- 生产力工具public.app-category.developer-tools- 开发工具public.app-category.utilities- 实用工具
Windows 配置
win: {
target: [
{ target: 'nsis', arch: ['x64'] }
],
icon: 'build/icon.ico' // 256x256 ico 格式
},
nsis: {
oneClick: false, // 非一键安装，允许用户选择目录
allowToChangeInstallationDirectory: true,
createDesktopShortcut: true,
createStartMenuShortcut: true,
shortcutName: 'My App'
}
typescript
Linux 配置
linux: {
target: ['AppImage'],
icon: 'build/icon.png', // 512x512 PNG 格式
category: 'Development'
}
typescript
公共配置项说明
| 配置项 | 类型 | 说明 |
|---|---|---|
appId | string | 应用唯一标识（反向域名格式） |
productName | string | 应用显示名称 |
directories.output | string | 打包输出目录 |
directories.buildResources | string | 构建资源目录（图标等） |
files | string | 包含/排除的文件模式 |
asar | boolean | 是否使用 asar 归档（默认 true） |
compression | 'store' | 'normal' | 'maximum' | 压缩级别 |
打包命令
# 打包当前平台
npx electron-builder build
# 打包指定平台
npx electron-builder build --mac
npx electron-builder build --win
npx electron-builder build --linux
# 打包所有平台
npx electron-builder build --mac --win --linux
# 不构建直接打包（跳过 vite build）
npx electron-builder build --dir
bash
图标资源准备
| 平台 | 格式 | 尺寸 | 文件位置 |
|---|---|---|---|
| macOS | .icns | 512x512 | build/icon.icns |
| Windows | .ico | 256x256 | build/icon.ico |
| Linux | .png | 512x512 | build/icon.png |
推荐使用 electron-icon-builder 从一张 1024x1024 的 PNG 图片自动生成所有平台图标。
实践要点
mac配置是所有 macOS 打包格式（dmg/pkg/zip）的公共配置，子格式继承这些设置- Windows 推荐使用 NSIS 格式（Squirrel 格式已废弃）
appId必须使用反向域名格式（如com.company.appname），影响后续的自动更新和代码签名- 开发阶段使用
--dir参数跳过安装包打包，加快调试速度 - 参考 Awesome Electron 和官方应用列表中知名应用的 electron-builder 配置文件学习最佳实践
↑